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XA APIs 


DB2 UDB for iSeries provides two sets of XA APIs: 
e XA APIs for Transaction Scoped Locks 


e XA APIs for Job Scoped Locks 


Before you use the XA APIs, you should read the following publications, which describe the X/Open 
Distributed Transaction Processing model in detail. 


e X/Open Guide, February 1996, Distributed Transaction Processing: Reference Model, Version 3 
(ISBN:1-85912-170-5, G504), The Open Group. 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


The model consists of five basic components: 


e An application program, which defines transaction boundaries and specifies actions that constitute 
a transaction. 


e Resource managers, such as databases or file access systems, which provide access to resources. 


e A transaction manager, which assigns identifiers to transactions, monitors their progress, and takes 
responsibility for transaction completion and for coordinating failure recovery. 


e Communications resource managers, which control communications between distributed 
applications within or across transaction manager domains. 


e A communications protocol, which provides the underlying communications between distributed 
applications. The protocol is supported by protected resource managers. 


This section explains the use of DB2 UDB for iSeries as an X/Open-compliant resource manager, and 
therefore is concerned only with the first three components of this model. More specifically, it documents 
the XA interface, which is the portion of the XA Distributed Transaction Processing model that transaction 
managers and resource managers use to communicate. The XA interface is a bidirectional interface, which 
consists of a set of UNIX-type APIs. 


The XA specification requires the resource manager to provide a switch that gives the transaction manager 
access to these APIs. The switch allows an administrator to change the set of resource managers that are 
linked with a program without having to recompile the application. This switch is a data structure that 
contains the resource manager's name, non-null pointers to the resource manager's APIs, a flag, and a 
version word. 


2*DB2 UDB for iSeries provides a switch for each set of XA APIs. Each switch is exported by the 
QTNXADTP service program. The switch for the XA APIs for Transaction Scoped Locks is called 
xa_switch. The switch for the XA APIs for Job Scoped Locks is called db2xa_switch. The flags in each 
switch provide information about the resource manager including the facts that migration of associations is 
not supported and asynchronous requests are not allowed. They also contain an array of procedure pointers 
that give addressability to the XA APIs. The XA APIs are typically called by a transaction manager using 
these pointers rather than by name. This precludes the transaction manager from having to know the actual 
function names and from having to link to the service program that actually contains the functions.“ 


The XA specification requires each resource manager to provide a header file that defines data structures 
and constants common to the operation of transaction managers and resource managers. The DB2 UDB for 
iSeries XA resource manager ships two header files in file H, library QSYSINC. Member XA contains a 
header file that is compatible with the XA architecture. Member QTNXADTP contains a header file that is 


not compatible with the XA architecture. Some of the structure and variable names in header file 
QTNXADTP have the prefix "db2." Either file can be used, but it is recommended that the XA header file 
be used rather than the QTNXADTP header file. The examples at the end of the XA APIs assume you use 
the XA header file. 


“If you are running XA transactions against a database that resides on the local system, you should use the 
XA APIs for Transaction Scoped Locks. These APIs have fewer restrictions than the XA APIs for Job 
Scoped Locks, and provide better performance in the following situations: 


e If multiple SQL connections are ever used to work on a single XA transaction branch. 


e If asingle SQL connection is used to work on multiple, concurrent XA transaction branches. 


In these situations, a separate job must be started to run XA transaction branches when the XA APIs for Job 
Scoped Locks are used. 


If you are running against a database that resides on a remote system, the XA APIs for Job Scoped Locks 
must be used. 


See Commitment Control for additional information on commitment control and XA transactions. 


Restrictions 


2Transactions that require the use of an XA resource manager must be performed in SQL server jobs. An 
SQL server job is a job whose server mode for Structured Query Language attribute has been set to *YES. 
Use the Change Job (QWTCHGJOB) API to control the setting of this attribute. The xa_open() and 
db2xa_open() APIs will set the server mode attribute to * YES if the attribute has not already been set. 
“For additional information about SQL server job, see DB2 UDB for iSeries SQL Programming Concepts 


in the Information Center and the question on What is CLI Server Mode? in the DB2 Universal Database 


for iSeries SQL CLI Frequently Asked Questions 4 


X/Open applications are only allowed to use SQL interfaces to access resources managed by DB2 UDB for 
iSeries. Both the embedded and call level interface (CLI) SQL interfaces are supported. #*Local relational 
databases may be used by the application when running with the XA APIs for Transaction Scoped Locks or 
the XA APIs for Job Scoped Locks. Local databases include those defined for an Indpendent ASP. Remote 
relational databases may be used by the application only when running with the XA APIs for Job Scoped 
Locks. “£When using a remote relational database, the RDB connection method must be Distributed Unit of 
Work (*DUW), and the remote location may be defined for either TCP/IP or SNA LU6.2 connections. 


The following interfaces are not supported for use by an X/Open application: 


e Control language (CL) or high-level language (HLL) interfaces for local files or distributed data 
management (DDM) files. 


e The Process Extended Dynamic SQL (QSQPRCED) API. 
e@ The Query (QQQQRY) API. 


e The commitment control API interfaces documented in the Journal and Commit APIs part. 


It is expected that most transaction managers will use the same user profile for all SQL connections. #*If 
the xa_open or db2xa_open APIs are used before the connections are started, this can be accomplished by 
specifying the same user profile for the *xainfo parameter of each xa_open() or db2xa_open() API call. 
XA applications generally do not use the resource manager's native security mechanisms to limit access to 
data. Rather, this is done at the application or transaction manager level. 
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XA APIs for Transaction Scoped Locks 


The following XA APIs for Transaction Scoped Locks are provided by the DB2 UDB for iSeries XA 
resource manager for use by a transaction manager: 


e *xa_close() (Close an XA Resource Manager (Transaction Scoped Locks)) closes a currently open 
resource manager in the thread of control.*& 


e@ xa_commit() (Commit an XA Transaction Branch (Transaction Scoped Locks)) commits the 
work associated with *xid.& 

e xa_complete() (Test Completion of Asynchronous XA Request) waits for the completion of an 
asynchronous operation.“ 

@ %xa_end() (End Work on an XA Transaction Branch (Transaction Scoped Locks)) is called when 
when an application thread of control finishes or needs to suspend work on a transaction branch.%& 

e xa_forget() (Forget an XA Transaction Branch (Transaction Scoped Locks)) is called to forget 
about a heuristically completed transaction branch.*& 

e xa_open() (Open an XA Resource Manager (Transaction Scoped Locks)) is called to open the 


XA resource manager and to prepare it for use in the XA distributed transaction environment. 


@ %xa_prepare() (Prepare to Commit an XA Transaction Branch (Transaction Scoped Locks)) is 


called to request that a resource manager prepare for commitment any work performed on behalf of 
*yid *& 


@ %xa_recover() (Recover XA Transaction Branches (Transaction Scoped Locks)) is called during 
recovery to obtain a list of transaction branches that are currently in a prepared or heuristically 
completed state.“ 


e %xa_rollback() (Roll Back an XA Transaction Branch (Transaction Scoped Locks)) is called to roll 
back work performed on behalf of the transaction branch.%& 
e %xa_start() (Start an XA Transaction Branch (Transaction Scoped Locks)) informs a resource 


manager that an application may do work on behalf of a transaction branch.*& 


e xa_start_2() (Start an XA Transaction Branch, Extended Version (Transaction Scoped Locks)) 
informs a resource manager that an application may do work on behalf of a transaction branch. 


The following example shows the interactions between the application program, transaction manager, and 
the XA resource manager during a typical transaction branch when the XA APIs for Transaction Scoped 
Locks are used. The actual interactions that occur during a transaction will vary depending on factors such 
as the following: 


e Whether the transaction is committed or rolled back 
e Whether the one- or two-phase commit protocol is used with the XA resource manager 


e Whether multiple threads are used to perform the work of a transaction branch 
Refer to the X/Open XA Specification for details. 


Example Using XA APIs for Transaction Scoped Locks 


HLL XA XA 
Application Transaction Resource 
Program Manager Manager 


1. tx_open =sSh5 > Xa_open --- - > 


<---------- <----------- 
XID xxx 
2 tx_begin ----- -> xa_start ------------— > 
<---------- <----------- 
3.  <SQL work> - - —> 
<-- ame ae aa en ra = ae —_ el 
4. 
5. tx_commit -------- > xa_end --------------> 
< pa a ae ey nee een, Seed 
6 xa_prepare ------> 
< Gd nh mee mr ela one at 
7 xa_commit ----------- > 
<---------- <----------- 
Notes 


1. The application uses the X/Open Transaction Demarcation (TX) tx_open() interface to open all the 
resource managers that are linked with the transaction manager. The transaction manager uses the 
xa_open() interface to open an instance of the XA resource manager. The transaction manager may 
open multiple XA resource managers that will participate in XA transactions. The transaction 
manager assigns a resource manager identifier (ID) to each resource manager instance. The 
resource manager ID uniquely identifies the instance within the thread of control in which the 
application is running. 


2. The application uses the TX tx_begin() interface to begin a transaction. For each resource manager 
that will participate in XA transactions, the transaction manager generates a transaction branch 
identifier (XID) and uses the XA xa_start() interface to start a transaction branch. 


3. The application uses SQL interfaces to access resources managed by DB2 UDB for iSeries. 
4. The application continues its transaction. It may access other resource managers as appropriate. 


5. When the transaction has been completed, the application uses the TX tx_commit() interface to 
commit the work. The transaction manager uses the XA xa_end() interface to end the transaction 
branch. 


6. The transaction manager uses the XA xa_prepare() interface to prepare the resources for 
commitment. 


7. The transaction manager uses the XA xa_commit() interface to commit the resources after all the 
resource managers involved in the transaction have successfully prepared their resources for 
commitment. When the commit operation is complete, the application can begin another transaction 


using the TX tx_begin() interface. 
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»xa_close()-- Close an XA Resource Manager 
(Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_close_entry(char *xa_info, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_close() to close a currently open resource manager in the thread of control. 
After this call, the resource manager cannot participate in global transactions on behalf of the calling thread 
until it is reopened. 


Parameters 


xa_info 


(Input) A pointer to a 256-byte, null-terminated character string that contains information used to 
close the resource manager. No information is currently allowed in this string. It must be a null 
string or contain only blanks with a null terminator. 


rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 
flags 
(Input) The following are valid settings of flags. 
TMNOFLAGS: OxQOQOOQ000L Perform the close operation normally. 
Authorities 


None 


Return Value 


-6 [XAER_PROTO] 
xa_close() was not successful. The function was called in an improper context. 
-5 [XAER_INVAL] 
xa_close() was not successful. Incorrect arguments were specified. 
-3 [XAER_RMERR] 
xa_close() was not successful. The resource manager detected an error when it closed the resource. 
-2. [XAER_ASYNC] 
xa_close() was not successful. The resource manager does not support asynchronous operations. 
0 [XA_OK] 


xa_close() was successful. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
char *xa_info; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_close_entry(xa_info, rmid, flags); 


} 
€ 
API introduced: V5R2 
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»xa_commit()-- Commit an XA Transaction 
Branch (Transaction Scoped Locks 


Syntax 


#include <xa.h> 
int xa_switch.xa_commit_entry(XID *xid, 


int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_commit() to commit the work associated with *xid. All changes that were 
made to resources managed by DB2 UDB for iSeries during the transaction branch are made permanent. 


Parameters 


xid 
(Input) A pointer to the transaction branch identifier. This identifier was generated by the 
transaction manager when the transaction branch was started. 


rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 


flags 
(Input) Following are the valid settings of flags. 
TMNOWAIT: 0x10000000L Do not commit the transaction if a blocking condition exists. 


TMONEPHASE: 0x40000000L Use the one-phase commit optimization for the specified 
transaction branch. 


TMNOFLAGS: OxO0000000L Use if no other flags are set. 


Authorities 


None 


Return Value 


The following values may be returned only if TMONEPHASE(0x40000000L) was set in the flags 
parameter. 


100 [XA_RBROLLBACK] 
The transaction branch was rolled back for an unspecified reason. 
101 [XA_RBCOMMFAIL] 
A communications failure occurred within the resource manager. 
102, [XA_RBDEADLOCK] 
A deadlock condition was detected within the resource manager. 
103 [XA_RBINTEGRITY] 
The resource manager detected a violation of the integrity of its resources. 
104 [XA_RBOTHER] 
The resource manager rolled back the transaction branch for a reason not on this list. 
105 [XA_RBPROTO] 
A protocol error occurred in the resource manager. 
106 [XA_RBTIMEOUT] 
A timeout occurred in the resource manager. 
107 [XA_RBTRANSIENT] 


A transient error was detected in the resource manager. 


The following values may be returned for all flags settings. 
-7 [XAER_RMFAIL] 
An error occurred that makes the resource manager unavailable. 
-6 [XAER_PROTO] 
xa_commit() was not successful. Function was called in an improper context. 
-5 [XAER_INVAL] 


xa_commit() was not successful. Incorrect arguments were specified. 


-4 [XAER_NOTA] 
The specified xid is not known by the resource manager. 
-3 [XAER_RMERR] 


xa_commit() was not successful. The resource manager detected an error when committing the 
transaction branch. 


-2 [XAER_ASYNC] 
xa_commit() was not successful. The resource manager does not support asynchronous operations. 
0 [XA_OK] 
xa_commit() was successful. 
4  [XA_RETRY] 
The resource manager is unable to commit the transaction branch at this time. 
TMNOWAIT(Ox10000000L) was set and a blocking condition exists. All resources held on behalf of 


*xid remain in a prepared state. The transaction manager should issue xa_commit() again at a later 
time. 


5  [XA_HEURMIX] 
Work on the transaction branch was partially committed and partially rolled back. 
6 [XA_HEURRB] 
Work on the transaction branch was heuristically rolled back. 
7 [XA_HEURCOM] 
Work on the transaction branch was heuristically committed. 
& [XA_HEURHAZ] 


Work on the transaction branch may have been heuristically completed. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_commit_entry(xid, rmid, flags); 


} 
€& 
API introduced: V5R2 
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»xa_complete()--Test Completion of 
Asynchronous XA Request (Transaction 
Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_complete_entry(int *handle, 
int *retval, int rmid, long flags) 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_complete() to wait for the completion of an asynchronous operation. 
Asynchronous operations are not supported by the DB2 UDB for iSeries resource manager. This function is 
provided only for compliance with the X/Open XA Specification. 


Parameters 


handle 
(Input) A pointer to an integer value returned by an XA function that had TMASYNC specified. 


retval 
(Output) A pointer to the integer return value of the asynchronous function. 

rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 

flags 


(Input) The follow are valid settings of flags. 
TMMULTIPLE: 0x00400000L Test completion of any outstanding asynchronous operation. 
TMNOWAIT: 0x10000000L Test for completion without blocking. 


TMNOFLAGS: OxOQ0000000L Use if no other flags are set. 


Authorities 


None 


Return Value 


-6 [XAER_PROTO] 


xa_complete() was not successful. TMUSEASYNC 0x00000004L was not set in the flags element of 
the XA resource manager's xa_switch_t structure. Asynchronous operations are not supported. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


% 


API introduced: V5R2 
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»xa_end()--End Work on an XA Transaction 
Branch (Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_end_entry (XID *xid, int rmid, 
long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_end() when an application thread of control finishes or needs to suspend 
work on a transaction branch. When xa_end() successfully returns, the calling thread of control is no longer 
associated with the transaction branch, but the branch still exists. 


If the TMSUSPEND flag is not specified, all SQL cursors used while the thread was associated with this 
transaction branch are closed. Files left open by a procedure, trigger or function that used legacy file access 
methods are closed regardless of flag settings. 


Parameters 


*xid 
(Input) A pointer to the transaction branch identifier. This identifier was generated by the 
transaction manager when the transaction branch was started. 


rmid 


(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 


flags 


(Input) The following are valid settings of flags. One, and only one, of TMSUSPEND, 
TMSUCCESS, or TMFAIL must be set. 


TMSUSPEND: 0x02000000L Suspend a transaction branch on behalf of the calling thread. The 
transaction manager must resume or end the suspended association in the current thread. 


TMSUCCESS: 0x04000000L The portion of work has succeeded. 


TMFAIL: 0x20000000L The portion of work has failed. 


Authorities 


None 


Return Value 


The following return codes indicate that the resource manager has marked the work performed on this 
transaction branch as rollback-only. 


100 


101 


102 


103 


104 


105 


106 


107 


[XA_RBROLLBACK] 

The transaction branch was marked rollback-only for an unspecified reason. 
[XA_RBCOMMFAIL] 

A communications failure occurred within the resource manager. 
[XA_RBDEADLOCK] 

A deadlock condition was detected within the resource manager. 
[XA_RBINTEGRITY] 

The resource manager detected a violation of the integrity of its resources. 
[XA_RBOTHER] 

The resource manager marked the transaction branch rollback-only for a reason not on this list. 
[XA_RBPROTO] 

A protocol error occurred in the resource manager. 

[XA_RBTIMEOUT] 

A timeout occurred in the resource manager. 

[XA_RBTRANSIENT] 


A transient error was detected by the resource manager. 


Other return codes: 


-7 


-6 


-5 


[XAER_RMFAIL] 

An error occurred that makes the resource manager unavailable. 
[XAER_PROTO] 

Function was called in an improper context. 

[XAER_INVAL] 


Incorrect arguments were specified. 


-4 [XAER_NOTA] 
The specified *xid is not known by the resource manager. 
-3 [XAER_RMERR] 


xa_end() was not successful. The resource manager detected an error when ending the transaction 
branch. 


-2 [XAER_ASYNC] 

xa_end() was not successful. The resource manager does not support asynchronous operations. 
0 [XA_OK] 

xa_end() was successful. 
9 [XA_NOMIGRATE] 

The resource manager was unable to prepare the transaction context for migration. The resource 


manager has suspended the association. The transaction manager can resume the association in the 
current thread only. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_end_entry(xid, rmid, flags); 


} 
& 
API introduced: V5R2 
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»xa_forget()-- Forget an XA Transaction Branch 
(Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_forget_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_forget() to forget about a heuristically completed transaction branch. After 
this call, the *xid is no longer valid. 


Parameters 


*xid 
(Input) A pointer to the transaction branch identifier. This identifier was generated by the 
transaction manager when the transaction branch was started. 


rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 
flags 
(Input) The following are valid settings of flags. 
TMNOFLAGS: OxQOOQOO000L Perform the forget operation normally. 
Authorities 


None 


Return Value 


% 


-6 


5 


4 


-2 


[XAER_RMFAIL] 

An error occurred that makes the resource manager unavailable. 
[XAER_PROTO] 

xa_forget() was not successful. Function was called in an improper context. 
[XAER_INVAL] 

xa_forget() was not successful. Incorrect arguments were specified. 
[XAER_NOTA] 

The specified xid is not known by the resource manager. 

[XAER_RMERR] 


xa_forget() was not successful. The resource manager detected an error when forgetting the 
transaction branch. 


[XAER_ASYNC] 
xa_forget() was not successful. The resource manager does not support asynchronous operations. 
[TM_OK] 


xa_forget() was successful. 


Error Messages 


The following messages may be sent from this function. 


Message ID Error Message Text 


CPE3S41I8 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int xrmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_forget_entry(xid, rmid, flags); 


} 
€ 
API introduced: V5R2 
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»xa_open()--Open an XA Resource Manager 
(Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_open_entry(char *xa_info, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_open() to open the XA resource manager and to prepare it for use in the 
XA distributed transaction environment. This function must be called before any other resource manager 
(xa_) calls are made. 


Parameters 


*xa_info 


(Input) A pointer to a null-terminated string that contains information used to initialize the resource 
manager. See the Usage Notes for details on what this string should contain. 


rmid 
(Input) A number generated by the transaction manager to identify this instance of the XA resource 
manager. This resource manager identifier is passed to the other XA functions to identify which 
instance of the resource manager for which the function is called. 

flags 
(Input) The following are valid settings of flags. 
TMNOFLAGS: OxQOOQ0O0000L Perform the open operation normally. 

Authorities 


None 


Return Value 


-6 [XAER_PROTO] 

xXa_open() was not successful. Function was called in an improper context. 
-5 [XAER_INVAL] 

xa_open() was not successful. Incorrect arguments were specified. 
-3 [XAER_RMERR] 


Xa_open() was not successful. The resource manager detected an error when opening the resource 
manager. 


-2 [XAER_ASYNC] 
xa_open() was not successful. The resource manager does not support asynchronous operations. 
0 [TM_OK] 


xa_open() was successful. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


e A pointer to the xa_info character string is passed on the xa_open() function. The character string 
contains information required by the XA resource manager. This information affects the behavior 
of DB2 UDB for iSeries when running as an XA resource manager. The xa_info string is a series of 
keyword specifications, each of which consists of: 


o A keyword. 
o The '=' character. 


o A keyword value. 


For example: 


TMNAME=YourTM RDBNAME=SYSABC lockwait=300 


e The restrictions on the data in the xa_info character string are: 


Oo 


There must be no blanks between the keyword and the '=' or between the '=' and the 
keyword value. 


The xa_info string must neither begin nor end with the '=' character. 
There must be at least one blank between each keyword specification. 


Keywords and keyword values, except the PASSWORD keyword value, are not 
case-sensitive; keyword values on system displays or messages are shown in uppercase. 
The PASSWORD keyword value is case-sensitive. 


If the PASSWORD keyword is specified, its value is assumed to be represented in the job 
default CCSID of the job that calls the xa_open() function. 


The xa_info string is limited to 1024 bytes and must be null-terminated. Note that this is 
longer than the 256 byte maximum architected in the XA Specification, however the longer 
length is required for iSeries long password support. If a null byte (‘00'x) is not found in the 
first 1024 bytes, [KAER_INVAL] is returned. 


The xa_info string value is treated as character data and is not converted. 


The return value [XKAER_INVAL] will be returned if a keyword is specified that is not 
documented in Figure 1. 


Figure 1. xainfo String Keywords and Values 


| Keyword Name | Keyword Value 


LOCKWAIT 


PASSWORD 


The maximum number of seconds that the system will wait on any lock request 
during transaction branches started by this thread. Lock wait time values that are 
specified by other system interfaces will be used only if they are smaller than this 
value. 


If not specified, lock wait time values specified by other system interfaces are used. 
The maximum value that may be specified is 999999999, 


The password to be used in conjunction with the user when accessing the relational 
database. This value is used only if the USER keyword is also specified. If 
specified, the password value is assumed to be represented in the job default CCSID 
of the job that calls the db2_xaopen() API. If the specified password value contains 
any null bytes (‘00'x) or blanks (‘40'x), the PWDLEN keyword must also be 
specified. The length of the password value must not exceed 512 bytes. 


If this keyword is not specified, PASSWORD defaults to 10 blanks. 


specified for this keyword is ignored. 


RDBNAME A 1- to 18-character name identifying the relational database that the transaction 
manager will use for XA transaction branches in this thread. If there is an entry in 
the relational database directory with Remote Location value “LOCAL, then special 
value *LOCAL may be used to identify that database. 

This is a required keyword. If this keyword is not specified, [KAER_INVAL] is 
returned. 

Once a thread calls xa_open() with a particular rmid and RDBNAME combination, 
the rmid may not be used on subsequent xa_open() calls unless the same 
RDBNAME value is used. Likewise, the RDBNAME value may not be used on 
subsequent xa_open() calls unless the same rmid is used. If a subsequent call is 
made with the same rmid and RDBNAME combination, but other values in the 


PWDLEN The length, in bytes, of the password. This value must not exceed 512. This 
keyword must be specified if the value specified for the PASSWORD keyword 
contains any null bytes ('00'x) or blanks ('40'x). If specified, the keyword must 
appear before the PASSWORD keyword. 

If this keyword is not specified, the length of the specified PASSWORD value is 
determined by the location of the first null byte (‘00'x) or blank ('40'x) following the 
PASSWORD keyword. If the PASSWORD keyword is not specified, the value 


xa_info string are different, the values on the first call remain in effect and a 
CPI836A informational message is sent to the joblog. 


must adhere to iSeries naming conventions. 


If this keyword is not specified, TMNAME defaults to blanks. 


USER A 1- to 10-character user profile to be used when accessing the relational database. 
This value will only be used if a user identifier and password is not specified on the 
Structured Query Language connection operation that follows the xa_open() request. 
If USER is not specified and no user profile is specified on the connection 
operation, the user profile for the connection defaults to the current user profile for 
the job that makes the connection. 
If this keyword is not specified, USER defaults to blanks. 


Related Information 


TMNAME A 1- to 10-character name identifying the XA transaction manager. Information is 
only significant for transaction managers that might require special processing and 
have worked with the XA resource manager to implement support. This value is 
displayed on the Display Commitment Definition Status panel when the 
commitment definition has been opened to act as an XA resource manager. 
Non-IBM applications must not use a name that starts with the letter Q. The name 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e@ X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 


Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 
main() { 


char xa_info[1024]= 
"tmname=mytranmgr rdbname=myrdb",; 


int rmid; 

long flags; 

int retcode; 

extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_open_entry(xa_info, rmid, flags); 


} 
€& 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»xa_prepare()-- Prepare to Commit an XA 
Transaction Branch (Transaction Scoped 
Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_prepare_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_prepare() to request that a resource manager prepare for commitment any 
work performed on behalf of *xid. The resource manager places all resources used in the transaction branch 
in a state that the changes can be made permanently when it later receives the xa_commit() request. All 
associations for *xid must have been ended by calling xa_end() prior to the prepare request. 


Parameters 


*xid 
(Input) A pointer to transaction branch identifier. This identifier was generated by the transaction 
manager when the transaction branch was started. 


rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 
flags 
(Input) The following are valid settings of flags. 
TMNOFLAGS: OxQOOQOOQ000L Perform the prepare operation normally. 
Authorities 


None 


Return Value 


The following return codes indicate that the resource manager has rolled back the work done on this 
transaction branch. 


100 [XA_RBROLLBACK] 
The transaction branch was rolled back for an unspecified reason. 
101 [XA_RBCOMMFAIL] 
A communications failure occurred within the resource manager. 
102, [XA_RBDEADLOCK] 
A deadlock condition was detected within the resource manager. 
103 [XA_RBINTEGRITY] 
The resource manager detected a violation of the integrity of its resources. 
104. [XA_RBOTHER] 
The resource manager rolled back the transaction branch for a reason not on this list. 
105 [XA_RBPROTO] 
A protocol error occurred in the resource manager. 
106 [XA_RBTIMEOUT] 
A time-out occurred in the resource manager. 
107 [XA_RBTRANSIENT] 


A transient error was detected in the resource manager. 


All other return codes: 
-7 [XAER_RMFAIL] 
An error occurred that makes the resource manager unavailable. 
-6 [XAER_PROTO] 
xa_prepare() was not successful. Function was called in an improper context. 
-5  [XAER_INVAL] 
xa_prepare() was not successful. Incorrect arguments were specified. 
-4 [XAER_NOTA] 


The specified xid is not known by the resource manager. 


-3 [XAER_RMERR] 


xa_prepare() was not successful. The resource manager detected an error when preparing the 
transaction branch. 


-2 [XAER_ASYNC] 

xa_prepare() was not successful. The resource manager does not support asynchronous operations. 
0 [XA_OK] 

xa_prepare() was successful. 
3  [XA_RDONLY] 


The transaction branch was read-only and has been committed. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_prepare_entry(xid, rmid, flags); 


} 
€ 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»xa_recover()-- Recover XA Transaction 
Branches (Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_recover_entry (XID *xids, 
long count, int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_recover() during recovery to obtain a list of transaction branches that are 
currently in a prepared or heuristically completed state. Multiple calls to this function can be made in a 
single recovery scan. The flags parameter defines when a recovery scan should start or end. 


Parameters 


*xids 
(Input) A pointer to an array into which the resource manager places XIDs for transaction branches 
in prepared or heuristically completed states. 


count 
(Input) The number of xids that fit into the xids array. 

rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 

flags 


(Input) The following are valid settings of flags. TMSTARTRSCAN: 0x01000000L Start a recovery 
scan and position the cursor to the start of the list. XIDs are returned from that point. 


TMENDRSCAN: Ox00800000L End a recovery scan after returning the XIDs. If this flag is used 
with the TMSTARTRSCAN flag, then a single xa_recover() call starts and ends the recovery scan. 


TMNOFLAGS: OxQ0OQ00000L Continue a recovery scan. XIDs are returned starting at the current 
cursor position. 


Authorities 


None 


Return Value 


-6 [XAER_PROTO] 

xa_recover() was not successful. Function was called in an improper context. 
-5 [XAER_INVAL] 

xa_recover() was not successful. Incorrect arguments were specified. 
-3 [XAER_RMERR] 


xa_recover() was not successful. The resource manager detected an error determining the XIDs 
to return. 


>= 0 The total number of XIDs returned in the xids array. 


Error Messages 


The following messages may be sent from this function. 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID xids[10]; 
int rmid; 
long count=10; 
long flags=TMSTARTRSCAN+TMENDRSCAN; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_recover_entry(xids, count, 
rmid, flags); 


} 
€ 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»xa_rollback()-- Roll Back an XA Transaction 
Branch (Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_rollback_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_rollback() to roll back work performed on behalf of the transaction branch. 
A transaction branch is capable of being rolled back until is has been successfully committed. 


Parameters 


*xid 
(Input) A pointer to the transaction branch identifier. This identifier was generated by the 
transaction manager when the transaction branch was started. 


rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 
identifies the resource manager. 
flags 
(Input) The following are valid settings of flags. 
TMNOFLAGS: OxQOQOO000L Perform the rollback operation normally. 
Authorities 


None 


Return Value 


The following return codes indicate that the resource manager rolled back the work done on this transaction 
branch. These values are typically returned when the transaction branch was previously marked 
rollback-only. 


100 [XA_RBROLLBACK] 
The transaction branch was rolled back for an unspecified reason. 
101 [XA_RBCOMMFAIL] 
A communications failure occurred within the resource manager. 
102, [XA_RBDEADLOCK] 
A deadlock condition was detected within the resource manager. 
103 [XA_RBINTEGRITY] 
The resource manager detected a violation of the integrity of its resources. 
104 [XA_RBOTHER] 
The resource manager rolled back the transaction branch for a reason not on this list. 
105 [XA_RBPROTO] 
A protocol error occurred in the resource manager. 
106 [XA_RBTIMEOUT] 
A timeout occurred in the resource manager. 
107  [XA_RBTRANSIENT] 


A transient error was detected in the resource manager. 


The following return codes may be returned for any flags setting. 
-7 [XAER_RMFAIL] 
An error occurred that makes the resource manager unavailable. 
-6 [XAER_PROTO] 
xa_rollback() was not successful. Function was called in an improper context. 
-5 [XAER_INVAL] 
xa_rollback() was not successful. Incorrect arguments were specified. 
-4 [XAER_NOTA] 


The specified xid is not known by the resource manager. 


-3 [XAER_RMERR] 


xa_rollback() was not successful. The resource manager detected an error when rolling back the 
transaction. 


-2 [XAER_ASYNC] 

xa_rollback() was not successful. The resource manager does not support asynchronous operations. 
0 [XA_OK] 

xa_rollback() was successful. 
5  [XA_HEURMIX] 

Work on the transaction branch was partially committed and partially rolled back. 
6 [XA_HEURRB] 

Work on the transaction branch was heuristically rolled back. 
7 [XA_HEURCOM] 

Work on the transaction branch was heuristically committed. 
& [XA_HEURHAZ] 


Work on the transaction branch may have been heuristically completed. 


Error Messages 


The following messages may be sent from this function. 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_rollback_entry(xid, rmid, flags); 


} 
& 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»xa_Start()-- Start an XA Transaction Branch 
(Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_start_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_start() to inform a resource manager that an application may do work on 
behalf of a transaction branch. The calling thread becomes associated with the transaction branch. 


Parameters 


*xid 
(Input) A pointer to the transaction branch identifier for the transaction branch that is to be 
associated with this thread. 

rmid 
(Input) An integer value that the transaction manager generated when calling xa_open(). The rmid 


identifies the resource manager. 


flags 
(Input) Following are the valid settings of flags. 
TMJOIN: 0x00200000L Caller is joining an existing transaction branch. 
TMRESUME: 0x08000000L Caller is resuming association with a suspended transaction branch. 


TMNOWAIT: 0x10000000L Do not associate the transaction branch with the thread if a blocking 
condition exists. 


TMNOFLAGS: OxQ0Q00000L To be used when no other flags are set. 


Authorities 


None 


Return Value 


The following return codes may be returned for any flags setting. 


-8 


-6 


-5 


4 


-3 


-2 


[XAER_DUPID] 


Neither TMRESUME nor TMJOIN were specified, and the xid already exists within the resource 
manager. 


[XAER_RMFAIL] 

An error occurred that makes the resource manager unavailable. 

[XAER_PROTO] 

xa_start() was not successful. Function was called in an improper context. 
[XAER_INVAL] 

xa_start() was not successful. Incorrect arguments were specified. 

[XAER_NOTA] 

TMRESUME or TMJOIN was specified, and the xid is not known by the resource manager. 
[XAER_RMERR] 


xa_start() was not successful. The resource manager detected an error when associating the 
transaction branch with the thread. 


[XAER_ASYNC] 

xa_start() was not successful. The resource manager does not support asynchronous operations. 
[XA_OK] 

xa_start() was successful. 

[XA_RETRY] 


TMNOWAIT was set in flags and a blocking condition exists. The thread was not associated with 
the transaction branch. 


The following return codes indicate that TMJOIN or TMRESUME was specified, and the specified 
transaction branch was not associated with the thread and is marked rollback-only. 


100 


[XA_RBROLLBACK] 


The transaction branch was marked rollback-only for an unspecified reason. 


101 


102 


103 


104 


105 


106 


107 


[XA_RBCOMMFAIL] 

A communications failure occurred within the resource manager. 
[XA_RBDEADLOCK] 

A deadlock condition was detected within the resource manager. 
[XA_RBINTEGRITY ] 

The resource manager detected a violation of the integrity of its resources. 
[XA_RBOTHER] 

The transaction branch was marked rollback-only for a reason not on this list. 
[XA_RBPROTO] 

A protocol error occurred in the resource manager. 

[XA_RBTIMEOUT] 

A timeout occurred in the resource manager. 

[XA_RBTRANSIENT] 


A transient error was detected in the resource manager. 


Error Messages 


The following messages may be sent from this function. 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 


Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e@ X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 


Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_start_entry(xid, rmid, flags); 


} 
& 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»xa_Start_2()--Start an XA Transaction Branch, 
Extended Version (Transaction Scoped Locks) 


Syntax 


#include <xa.h> 


int xa_switch.xa_start_2_entry(XID *xid, 
int rmid, XACTL *ctl, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls xa_start_2() to inform a resource manager that an application may do work on 
behalf of a transaction branch. The calling thread becomes associated with the transaction branch. 


For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_start() API. 


The xa_start_2() function is the same as the xa_start() function, with one additional parameter, ctl. 
*ctl 
(Input) A pointer to the following structure. 


struct xactl_t { 
long flags; /* valid element flags */ 
TRANSACTION_TIMEOUT timeout; /* timeout value */ 

}; 


Following are the valid settings of ctl->flags. 
XAOPTS_TIMEOUT: 0x00000001L Timeout value is present. 
XAOPTS_NOFLAGS: 0x00000000L To be used when no optional values are set. 


ctl->timeout is the number of seconds before which the resource manager can timeout and rollback 
the transaction. Type TRANSACTION_TIMEOUT is declared in header file xa.h. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 


XACTL ctl; 

long flags; 

int retcode; 

extern struct xa_switch_t xa_switch; 


retcode = 
xa_switch.xa_start_2_entry(xid, rmid, &ctl, flags); 


} 
€ 
API introduced: V5R2 
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XA APIs for Job Scoped Locks 


The XA APIs for Job Scoped Locks are: 


e db2xa_close( (Close an XA resource manager (Job Scoped Locks)) is called to close a currently 
open resource manager in the thread of control. 


e db2xa_commit() (Commit an XA transaction branch (Job Scoped Locks)) is called to commit the 
work associated with *xid. 


e db2xa_complete() (Test completion of an asynchronous XA request (Job Scoped Locks)) is called 
to wait for the completion of an asynchronous operation. 


e db2xa_endQ (End work on an XA transaction branch (Job Scoped Locks)) is called when an 
application thread of control finishes or needs to suspend work on a transaction branch. 

e db2xa_forget() (Forget an XA transaction branch (Job Scoped Locks)) is called to forget about a 
heuristically completed transaction branch. 


e@ db2xa_open(Q (Open an XA resource manager (Job Scoped Locks)) is called to open the XA 
resource manager and to prepare it for use in the XA distributed transaction environment. 


e@ db2xa_prepare() (Prepare to commit an XA transaction branch (Job Scoped Locks)) is called to 
request that a resource manager prepare for commitment any work performed on behalf of *xid. 


e db2xa_recover() (Recover XA transaction branches (Job Scoped Locks)) is called during recovery 


to obtain a list of transaction branches that are currently in a prepared or heuristically completed 
state. 


e db2xa_rollback(Q (Roll back an XA transaction branch (Job Scoped Locks)) is called to roll back 
work performed on behalf of the transaction branch. 


e db2xa_start() (Start an XA transaction branch (Job Scoped Locks)) is called to inform a resource 
manager that an application may do work on behalf of a transaction branch. 


The following exit functions must be provided by a transaction manager for use by the XA resource 
manager %* when the XA APIs for Job Scoped Locks are used: 


@ ax_reg() (Exit program to dynamically register an XA resource manager) 


@ ax_unreg() (Exit program to dynamically unregister an XA resource manager) 


The following example shows the interactions between the application program, transaction manager, and 
the XA resource manager during a typical transaction #*when the XA APIs for Job Scoped Locks are used. 
“The actual interactions that occur during a transaction will vary depending on factors such as the 
following: 


e Whether the transaction is committed or rolled back 
e Whether the one- or two-phase commit protocol is used with the XA resource manager 


e Whether multiple threads are used to perform the work of a transaction branch 
Refer to the X/Open XA Specification for details. 


Example Using XA APIs #for Job Scoped Locks 


HLL XA XA 
Application Transaction Resource 
Program Manager Manager 


<---------- <----------- 
2 tx_begin --------- > 
< SE ae Oe YC ee 
3 <SQOL-WOLk> Sass 2 55S seS SSS SSS SSeS SSSS= > 
4. qSoss=Ss5==> Call ax_reg 
XID xxx 
—---------- > 
< gl aa — 
Se 
6. tx _commit -------- > db2xa_end —--------> 
< i a mt i ep lng Se pc 
7 db2xa_prepare —-—--—-—— > 
< pe Se ga an pat al Gi tt es 
8 db2xa_commit -------- > 
<---------- <----------- 
Notes 


1. The application uses the X/Open Transaction Demarcation (TX) tx_open() interface to open all the 
resource managers that are linked with the transaction manager. The transaction manager uses the 
db2xa_open() interface to open an instance of the XA resource manager. The transaction manager 
may open multiple XA resource managers that will participate in XA transactions. The transaction 
manager assigns a resource manager identifier (ID) to each resource manager instance. The 
resource manager ID uniquely identifies the instance within the thread of control in which the 
application is running. An instance of the XA resource manager can be thought of as an SQL 
connection to the relational database specified on the *xainfo parameter of the db2xa_open() API. 


2. The application uses the TX tx_begin() interface to begin a transaction. 
3. The application uses SQL interfaces to access resources managed by DB2 UDB for iSeries. 


4. The XA resource manager uses the XA ax_reg() interface to dynamically register itself with the 
transaction manager. The transaction manager returns a transaction branch identifier (XID) that 
uniquely identifies the transaction branch. 


5. The application continues its transaction. It may access other resource managers as appropriate. 


6. When the transaction has been completed, the application uses the TX tx_commit() interface to 
commit the work. The transaction manager uses the XA db2xa_end{() interface to end the 
transaction branch. 


7. The transaction manager uses the XA db2xa_prepare() interface to prepare the resources for 
commitment. 


8. The transaction manager uses the XA db2xa_commit() interface to commit the resources after all 
the resource managers involved in the transaction have successfully prepared their resources for 
commitment. When the commit operation is complete, the application can begin another transaction 
using the TX tx_begin() interface. 


Restrictions for XA APIs for Job Scoped Locks 


When using the XA APIs for Job Scoped Locks, “San application that uses the CLI SQL interfaces must use 
a single connection to perform all work for a transaction branch. This means that if the XA join function is 
used so that multiple threads work on a single transaction branch, all the joining threads must use the same 
CLI connection for that work. Since CLI connection handles cannot be shared across jobs, this means that 
the XA join function can be used only by threads within a single job when using the CLI. This restriction 
does not apply when the application uses embedded SQL, #*or when the XA APIs for Transaction Scoped 
Locks are used. “ 


When used with #the XA APIs for Job Scoped Locks, “some aspects of SQL Server Mode behavior are 
affected. Traditional SQL Server Mode usage within an application makes a one to one correlation between 
a connection to the database in the application and to a QSQSRVR prestart job in the QSYSWRK 
subsystem. All SQL requests made in the application using that connection are executed in the correlated 
QSQSRVR job. When the connection is closed, the job is recycled and returned to the prestart job pool. 


With XA, an application has the ability to start and use separate transaction branches over a single database 
connection. #*When the XA APIs for Job Scoped Locks are used to start a new transaction branch “fusing a 
connection that was earlier used for a different transaction branch that has not yet been completed 
(committed or rolled back), the new transaction branch is assigned its own QSQSRVR job. This means a 
single connection can be related to multiple QSQSRVR jobs. When a transaction branch that requires a new 
QSQSRVR job completes, that QSQSRVR job is dissociated from the connection, recycled and returned to 
the prestart job pool. 


If embedded SQL is used and the native DB2 UDB for iSeries security mechanisms are used, the 
transaction manager must ensure that all work on a transaction branch is performed by jobs or threads using 
the same user profile. In other words, if the XA join function is used, every joining thread or job must use 
the same user profile as the thread or job that started the transaction branch; otherwise, a security exposure 
will exist. 2*This security consideration does not exist when using the XA APIs for Transaction Scoped 
Locks because the one to one correlation between the connection and the QSQSRVR job is always 
maintained, regardless of what transaction branch is being worked on. 


While this model works well for isolating transactions, the environment may provide some extra work on 
behalf of the application. Since separate and distinct jobs are in use for each transaction branch, any 
job/process-scoped resources setup while under one transaction branch will be unavailable once the 
application has switched to a different transaction branch. A list of the known limitations and restrictions 
when using this support is included below. This list is not guaranteed to be comprehensive. 


The following example demonstrates a scenario where these restrictions may be encountered. 
1. db2xa_open() 


2. SQL Connect. This may be skipped if connection is to start implicitly when the first embedded 
SQL request is made. 


3. Set up to have ax_reg() return TM_OK for XID1 when SQL work is requested. 


4. SQL statements to perform work. The first statement causes transaction branch XID1 to be created. 
The work for XID1 is done within SQL Server Mode Job: xxxxxx/QUSER/QSQSRVR). 


5. db2xa_end() with flag TMSUSPEND for XID1. 
6. Set up to have ax_reg() return TM_OK for XID2 when SQL work is requested. 


7. SQL statements to perform work. The first statement causes transaction branch XID2 to be created. 
The work for XID2 is done within SQL Server Mode Job: yyyyyy/QUSER/QSQSRVR). 


8. db2xa_end() with flag TMSUCCESS for XID2. 
9. Set up to have ax_reg() return TM_RESUME for XID1 when SQL work is requested. 


10. SQL statements to perform work . The first statement causes transaction branch XID1 to be 
resumed. The work for XID1 is done within SQL Server Mode Job: xxxxxx/QUSER/QSQSRVR). 


11. db2xa_end() with flag TMSUCCESS for XID1. 
12. db2xa_prepare() XID1. This may be requested from any thread. 
13. db2xa_commit() XID1. This may be requested from any thread. 


14. db2xa_prepare() XID2. This may be requested from any thread. 
15. db2xa_commit() XID2. This may be requested from any thread. 


SQL prepared statements 


When an application prepares an SQL statement, the resulting statement is stored in a job-scoped system 
space. This means that, for the example above, statements prepared while working on transaction branch 
XID1 are not available while working on transaction branch XID2, because the SQL work for the two 
transaction branches is done in separate QSQSRVR jobs. If the application attempts to use a prepared 
statement that is not available, the failure symptom would be SQLCODE = -518. (SQL0518 - Prepared 
statement &1 not found.) 


SQL Cursors 


SQL cursors are also job-scoped resources, so they are not available to the application after switching to a 
new transaction branch. If an application opens an SQL cursor and changes transaction branches, the cursor 
may remain open in the QSQSRVR job related to the previous transaction branch depending on how that 
branch was ended (see SQLHOLD Values). However, the cursor will not be available while working on the 


new transaction branch. If and when the original transaction branch is resumed, open cursors related to that 
transaction branch would again become available. Attempting to reference a cursor while executing under a 
transaction branch other than the one under which the cursor was opened, will result in a failure of 
SQLCODE = -501. (SQLO501 - Cursor &1 not open.) 


Result Sets 


When calling a stored procedure that returns result set(s), the application needs to take care to fully process 
the result sets before changing to a different transaction branch. SQL CLI services that return information 
about the status of a result set, could return incorrect information if not used in this manner. Examples of 


SQL CLI APIs that return information based on interim results are SQLNumResultColsQ), 
SQLDescribeCol(), SQLColAttributes() and SQLDescribeParam(). 


SQL CLI APIs like SQLFetch() and SQLFetchScroll(), which deal directly with the SQL result set cursor, 
would fail with SQLCODE = -502. (SQL0502 - Cursor &1 already open.) 


SET PATH statement 


The SET PATH SQL statement allows the application to designate a path to use for unqualified library 
access to SQL stored procedures, SQL triggers and SQL UDFs within a dynamic statement. The path is a 
job-scoped resource, and therefore not available after changing transaction branches. The application 
should repeat any SET PATH statements after a transaction branch change, if the path will still be needed. 


Other SQL considerations 


Applications should not change transaction branches while running within an SQL Stored Procedure, an 
SQL User Defined Function (UDF) or an SQL Trigger program. Results would be unpredictable and no 
anticipated failure information is available. 


Embedded SQL applications that use the QSQCHGDC() system API to set up the Dynamic Default 
Connection will not function correctly because the QSQCHGDC() will not affect the SQL Server Mode 
job. This has always been a restriction of the SQL Server Mode environment. If encountered, the failure 
symptom seen by the application would be SQLCODE = -204. (&1 in &2 type *&3 not found.) 


Note that SQL CLI users that set the default library using the SQLSetConnectAttr() API with the 
SQL_ATTR_DBC_DEFAULT_LIB connection attribute will continue to work. SQL CLI connection 
attributes are still in place after moving to a different transacation branch. 


Top | UNIX-Type APIs | APIs by category 


db2xa_close()--Close an XA Resource Manager 
»(Job Scoped Locks)« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_close_entry(char *xa_info, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_close() to close a currently open resource manager in the thread of 
control. After this call, the resource manager cannot participate in global transactions on behalf of the 
calling thread until it is reopened. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_close() API. 


Example 


#include <xa.h> 


main() { 
char *xa_info; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_close_entry(xa_info, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_commit()--Commit an XA Transaction 
Branch »(Job Scoped Locks)<« 


Syntax 


#include <xa.h> 
int db2xa_switch.xa_commit_entry (XID *xid, 


int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_commit() to commit the work associated with *xid. All changes that 
were made to resources managed by DB2 UDB for iSeries during the transaction branch are made 
permanent. 


# For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_commit() API. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_commit_entry(xid, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_complete()--Test Completion of 
Asynchronous XA Request (Job Scoped 
Locks) 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_complete_entry(int *handle, 
int *retval, int rmid, long flags) 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_complete() to wait for the completion of an asynchronous operation. 
Asynchronous operations are not supported by the DB2 UDB for iSeries resource manager. This function is 
provided only for compliance with the X/Open XA Specification. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_complete() API. 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_end()--End Work on an XA Transaction 
Branch »(Job Scoped Locks)« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_end_entry(XID *xid, int rmid, 
long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_end() when an application thread of control finishes or needs to 
suspend work on a transaction branch. When db2xa_end() successfully returns, the calling thread of 
control is no longer associated with the transaction branch, but the branch still exists. 


SQL cursors used while the thread was associated with this transaction branch may be closed. Refer to the 
SQLHOLD keyword description in the usage notes of the db2xa_open() API for details. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_end() API. <a 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int xrmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_end_entry(xid, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_forget()--Forget an XA Transaction 
Branch »(Job Scoped Locks)<« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_forget_entry (XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_forget() to forget about a heuristically completed transaction branch. 
After this call, the *xid is no longer valid. 


®* For additional information about parameters, authorities required, and error conditions, see the 


xa_forget() API. & 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_forget_entry(xid, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_open()--Open an XA Resource Manager 
»(Job Scoped Locks)« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_open_entry(char *xa_info, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_open() to open the XA resource manager and to prepare it for use in the 
XA distributed transaction environment. This function must be called before any other resource manager 
(db2xa_) calls are made. 


* For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_open() API. 


Usage Notes 


2» The usage notes for the xa_open() API apply to this API with the following differences. 


e Additional xa_info keywords shown in Figure 1-4 are allowed. 


e = The LOCKWAIT xa_info keyword is not allowed. 


Figure 1-4. xainfo String Keywords and Values 


| Keyword Name | Keyword Value 


DFTJRN Default Journal. See the online help for the DFTJRN keyword of the STRCMTCTL 
CL command for a description of the effect of this keyword. The journal should be 
specified as the journal's library, concatenated with a '/’, concatenated with the 
journal's name (for example, MYLIB/MYJRN). Both the library and journal name 
must follow iSeries conventions for naming system objects. 


The special value *NONE is supported for default journal. 


The special value *LIBL is accepted for the library portion of the default journal and 
is the default if the library portion is not specified. 


If this keyword is not specified, no default journal is used. 


If this keyword is specified but unresolvable, [XAER_INVAL] is returned. 


OMTJRNE 


SQLHOLD 


SRVPGM 


Omit Journal Entries. See the online help for the OMTJRNE keyword of the 


STRCMTCTL CL command for a description of the effect of this keyword. 


N_ Corresponds to the STRCMTCTL OMTJRNE value *NONE. 
L_ Corresponds to the STRCMTCTL OMTJRNE value *LUWID. 


If this keyword is not specified, OMTJRNE defaults to N. 


SQL HOLD value. Whether SQL cursors are closed during some XA operations. 
Refer to SQLHOLD Values for detailed information about this keyword. 


If this keyword is not specified, SQLHOLD defaults to A. 


The name of a library qualified service program that contains functions ax_reg() 
and ax_unreg() to be called by the resource manager to register and unregister itself 
with the transaction manager. The service program should be specified as the 
program's library, concatenated with a '/’, concatenated with the program's name (for 
example, TMLIB/TMPGM). Both the library and program name must follow iSeries 
conventions for naming system objects. 


The special value *LIBL is supported for the library portion of the service program 
and is the default if the library portion is not specified. 


This is a required keyword. If this keyword is not specified, or is unresolvable, 
[XAER_INVAL] is returned. 


See ax_reg()--Exit Program to Dynamically Register an XA Resource Manager and 


ax_unreg()--Exit Program to Dynamically Unregister an XA Resource Manager for 


details on these service functions. 


SQLHOLD Values 


This section documents how the SQLHOLD keyword value affects SQL cursors during the following XA 
operations (other XA operations do not affect cursors): 


e@ db2xa_end() unless the TUSUSPEND flag is specified 
e db2xa_commit() 
e db2xa_rollback() 


This applies only to cursors associated with the connection that is used for the transaction branch affected 
by the XA operation. As shown below, cursors declared WITH HOLD are treated differently in some cases 
than those not declared WITH HOLD. Note that cursors can be declared WITH HOLD only when 
embedded SQL is used. CLI cursors are not declared WITH HOLD. 


A Cursors are affected by XA operations as follows: 
e db2xa_end() with the TMSUCCESS or TMFAIL flag: 
o All cursors are closed. 
e@ db2xa_commit(): 
o Cursors are not affected since db2xa_end() already closed them. 


e@ db2xa_rollback(): 


o Cursors are not affected since db2xa_end() already closed them. 


E Cursors are affected by XA operations as follows: 

e db2xa_end() with the TMSUCCESS or TMFAIL flag: 
Oo Cursors declared WITH HOLD are held open. 
o Cursors not declared WITH HOLD are closed. 

e@ db2xa_commit(): 
Oo Cursors declared WITH HOLD are held open. 
o Cursors not declared WITH HOLD are closed. 

e@ db2xa_rollback(): 


o Allcursors are closed. 


L_ Cursors are affected by XA operations as follows: 
e@ db2xa_end() with the TMSUCCESS or TMFAIL flag: 
o All cursors are held open. 
e@ db2xa_commit(): 
o If the relational database resides on an iSeries system: 
m All cursors are left open. 
o If the relational database does not reside on an iSeries system: 
m Cursors declared WITH HOLD are left open. 
m Cursors not declared WITH HOLD are closed. 
e@ db2xa_rollback(): 
o If the relational database resides on an iSeries system: 
mw All cursors are left open. 
o If the relational database does not reside on an iSeries system: 


m All cursors are closed. 


N_ Cursors are affected by XA operations as follows: 
e db2xa_end() with the TMSUCCESS or TMFAIL flag: 
o All cursors are held open. 
e@ db2xa_commit(): 
o Cursors declared WITH HOLD are held open. 
o Cursors not declared WITH HOLD are closed. 
e@ db2xa_rollback(): 


o Allcursors are closed. 


Y Cursors are affected by XA operations as follows: 
e db2xa_end() with the TMSUCCESS or TMFAIL flag: 
o All cursors are held open. 
e@ db2xa_commit(): 
o If the relational database resides on an iSeries system: 
m All cursors are left open. 
oO If the relational database does not reside on an iSeries system: 


mw The db2xa_commit() operation will fail. This value should not be used with 
relational databases that do not reside on an iSeries system. 


e@ db2xa_rollback(): 
o If the relational database resides on an iSeries system: 
m All cursors are left open. 
oO If the relational database does not reside on an iSeries system: 


m The db2xa_rollback() operation will fail. This value should not be used with 
relational databases that do not reside on an iSeries system. 


Example 


#include <xa.h> 
main() { 


char xa_info[1024]= 
"tmname=mytranmgr srvpgm=tmlib/tmserv rdbname=myrdb"; 


int xrmid; 

long flags; 

int retcode; 

extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_open_entry(xa_info, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_prepare()--Prepare to Commit an XA 
Transaction Branch »(Job Scoped Locks)<« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_prepare_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_prepare() to request that a resource manager prepare for commitment 
any work performed on behalf of *xid. The resource manager places all resources used in the transaction 
branch in a state that the changes can be made permanently when it later receives the db2xa_commit() 
request. All associations for *xid must have been ended by calling db2xa_end() prior to the prepare 
request. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_prepare() API. & 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int rmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_prepare_entry(xid, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_recover()--Recover XA Transaction 
Branches »(Job Scoped Locks)<« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_recover_entry (XID *xids, 
long count, int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_recover() during recovery to obtain a list of transaction branches that 
are currently in a prepared or heuristically completed state. Multiple calls to this function can be made in a 
single recovery scan. The flags parameter defines when a recovery scan should start or end. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_recover() API. 


Example 


#include <xa.h> 


main() { 
XID xids[10]; 
int rmid; 
long count=10; 
long flags=TMSTARTRSCAN+TMENDRSCAN; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_recover_entry(xids, count, 
rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_rollback()--Roll Back an XA Transaction 
Branch »(Job Scoped Locks)<« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_rollback_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_rollback() to roll back work performed on behalf of the transaction 
branch. A transaction branch is capable of being rolled back until is has been successfully committed. 


® For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_rolback() API. 


Example 


#include <xa.h> 


main() { 
XID *xid; 
int xrmid; 
long flags; 
int retcode; 
extern struct xa_switch_t db2xa_switch; 


retcode = 
db2xa_switch.xa_rollback_entry(xid, rmid, flags); 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


db2xa_start()--Start an XA Transaction Branch 
»(Job Scoped Locks)« 


Syntax 


#include <xa.h> 


int db2xa_switch.xa_start_entry(XID *xid, 
int rmid, long flags); 


Default Public Authority: *USE 


Service Program: QTNXADTP 


Threadsafe: Yes 


A transaction manager calls db2xa_start() to inform a resource manager that an application may do work 
on behalf of a transaction branch. 2 When using the XA APIs for Job Scoped Locks, * the XA resource 
manager does not use this function. It dynamically registers work done on behalf of a transaction by using 
the ax_reg() function. This function is provided only for compliance with the X/Open XA Specification. 


2 For additional information about parameters, authorities required, return values, and error conditions, see 


the xa_start() API. 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


ax_reg()--Exit Program to Dynamically Register 


an XA Resource Manager »(Job Scoped Locks) 
= 


Syntax 


#include <xa.h> 


int ax_reg(int rmid, XID *xid, long flags); 


Threadsafe: Conditional; see Usage Notes. 


The XA resource manager calls ax_reg() to inform a transaction manager that it is about to do work on 
behalf of an application in a thread of control. The transaction manager needs to tell the resource manager 
whether or not that work should be performed on behalf of a transaction branch. If the work is part of a 
transaction branch, the transaction manager will return the transaction branch identifier in *xid. If the work 
is not part of a transaction branch, the transaction manager will return the NULLXID in *xid. 


The XA resource manager indicates that it uses dynamic registration by setting the TMREGISTER value in 
the flags element of its xa_switch_t structure. 


The name of the service program that contains ax_reg() and ax_unreg() must be provided to the XA 
resource manager in the *xa_info parameter of the db2xa_open() call. 


Parameters 
rmid 


(Input) The resource manager identifier that was generated by a transaction manager when the 
resource manager was opened. 


*xid 
(Input) A pointer to the buffer where the transaction manager will store the generated transaction 
branch identifier. This identifier is associated with work done in the calling thread of control or 
with a NULLXID, which indicates that work is being done outside a transaction branch. 

flags 
(Input) The flags argument must be set to this value. TMNOFLAGS: Ox00000000L No flags are 
defined for this function. 

Authorities 


None 


Return Value 


Ee 


-2 


[TMER_PROTO] 

ax_reg() was not successful. Function was called in an improper context. 
[TMER_INVAL] 

ax_reg() was not successful. Incorrect arguments were specified. 
[TMER_TMERR] 


ax_reg() was not successful. The transaction manager detected an error when registering the 
resource. 


[TM_OK] 
ax_reg() was successful. 
[TM RESUME] 


The resource manager should resume work on a previously suspended transaction branch. If the 
resource manager does not recognize the *xid, it will return a failure indication to the application. 


[TM_JOIN] 


The resource manager is joining the work of an existing transaction branch. If the resource manager 
does not recognize the *xid, it will return a failure indication to the application. 


Usage Notes 


1. This function must be threadsafe if the transaction manager calls the XA APIs in a multithreaded 
job. 

2. Refer to Restrictions in the introduction to the XA APIs for restrictions when using the TM_JOIN 
return value. 


Related Information 


e@ X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 
Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Exit program introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


ax_unreg()--Exit Program to Dynamically 
Unregister an XA Resource Manager »(Job 
Scoped Locks)<« 


Syntax 


#include <xa.h> 


int ax_unreg(int rmid, long flags); 


Threadsafe: Conditional; see Usage Notes. 


The XA resource manager calls ax_unreg() to inform a transaction manager that it has completed work on 
a local transaction. The local transaction was started after receiving a NULLXID from ax_reg(). 


The XA resource manager indicates that it uses the dynamic registration facility by setting the 
TMREGISTER value in the flags element of its xa_switch_t structure. 


The name of the service program that contains ax_reg() and ax_unreg() must be provided to the XA 
resource manager in the *xa_info parameter of the db2xa_open() call. 


Parameters 


rmid 


(Input) The resource manager identifier that was generated by a transaction manager when the 
resource manager was opened. 


flags 
(Input) The flags argument must be set to this value. TMNOFLAGS: Ox00000000L No flags are 
defined for this function. 

Authorities 

None 


Return Value 


-3 [TMER_PROTO] 
ax_unreg() was not successful. Function was called in an improper context. 
-2. [TMER_INVAL] 


ax_unreg() was not successful. Incorrect arguments were specified. 


-1 [TMER_TMERR] 


ax_unreg() was not successful. The transaction manager detected an error when unregistering the 
resource. 


0 [TM_OK] 


ax_unreg() was successful. 


Usage Notes 
1. This function must be threadsafe if the transaction manager calls the XA APIs in a multithreaded 
job. 
Related Information 
e X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA 


Specification (ISBN: 1-872630-24-3, C193 or XO/CAE/91/300), The Open Group. 


e X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction 
Demarcation) Specification (ISBN: 1-85912-094-6, C504), The Open Group. 


Exit program introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


Header Files for UNIX-Type Functions 


Programs using the UNIX-type functions must include one or more header files that contain information 
needed by the functions, such as: 


e Macro definitions 
e Data type definitions 
e Structure definitions 
e Function prototypes 
The header files are provided in the QS YSINC library, which is optionally installable. Make sure 


QSYSINC is on your system before compiling programs that use these header files. For information on 
installing the QSYSINC library, see Data structures and the QSYSINC Library. 


The table below shows the file and member name in the QS YSINC library for each header file used by the 
UNIX-type APIs in this publication. 


Name of File in 
Name of Header File QSYSINC Name of Member 


[| arpa/ineth [| arpa/ineth [ ARPA [INET 


a 
a * 

tik | | so 
[  —sbseerrch CEC A~<“‘i‘~*Y:S*é‘éiBSEERRR 
[ss direnth [CM Rs—~<“i«i‘Cé«zYS)~OCéIRENT 
[ emoh [| H [ERRNO] | 
[_eph | SOS 

| evinttypes. h | | TNS 
ee ee ee 
[| %netinet/iemp6.h NETINE |  ICMP6& 
[| netinetinh NETINET [| WN 
| netinet/ip_icmp.h NETINET [|  IPICMP 


mo) oo) eo) eo) a) ee} ee} ey] 


| netinet/ip.h NETINET | IP 
| 2’netinet/ip6.h NETINET | IP6& 
| netinet/tcp.h NETINET TCP 


| netinet/udp.h NETINET UDP 

[netns/idph = | 0S NETNS) [CIDP 
[netns/ipxh = |S NETNS) [CPX 
[so netns/ns-h | NETNS) [CONST 
[so netns/sp-b |S NETNS) [SP 
[netrouteh = [)CNET)=—~<C;«é‘L”)~Ss*'<‘éROUTEECi:*s 
[—snettel/telLh «= sis[))sSNETTEL =o [)ti‘<‘STENRES—“( isis 


an 


[  oosh fC OS2 

[|  —sosddefh fC ASE S2DEF 
[ pwd fC PWD 

[0 gh fH QLG 

| —s qpOlfloph fs QPOLFLOP 
| Bqp0limih | | QPOLIRNLE 

| 2>qpOlror.h | | QPOLROR& 

|  qpOzolsm-h fC HH—C*ST ss QPOZOLSM 
| — qpOztrech fC QPOZTRE 
|  qpOztrmlh [| CSTs QPOZTRML 
| #qsoasync.h | | QSOASYNC% 
| qtnxaapi.h | QTNXAAPI 
[ qtnxadtph fC H——CSE ss QQTNXADTP 
|  qtomeapih sf] CM ™—C~@TSsC QQOMEEAP 


TRIG 


| qtossapi.h | H | QTOSSAPI 
| resolv.h | H | RESOLVE 


an 


| semaphore.h | | SEMAPHORE 


[signal | CMHC SIGNAL 
[|  spawnh Cf CM ™~“<~S SPAWN 
[ssh fA SSL 

| sysferrnoh = fC H™:~iT SC ERRNOU 
[| sysfioctLh SYS [|  IOCTL 
| ——ssys/ipeh SYS [ woe 


| sys/layout.h | H | LAYOUT 
| sys/limits.h | H | LIMITS 


| —ssys/msg-ho SYS MSG 

[| sys/param.h SYS [ PARAM 
| #*sys/resource.h SYS | RESOURCE® 

| —ssys/sem-h SYS SEM 

| sys/setimp.h SYS | ‘SETIMP 
| sys/shm.h SYS SHM 

[| sys/signalh SYS [ SIGNAL 
[| _sys/socketh SYS [SOCKET 
[| —sys/stath SYS [ STAT” 


| sys/statvfs.h SYS | STATVFS 


| —ssysfimeh SYS [| TIME 
[| sys/types.b SYS [TYPES si 
| —ssys/uio.h SYS UIO 

[ sys SYS [ UN 
| —ssys/waith SYS | WAIT 
| Sulimit.h H | ULIMIT*& 

[| sounistdh fC HSE UNISTD 
[  soutimeh fC UTIME 


You can display a header file in QS YSINC by using one of the following methods: 


e Using your editor. For example, to display the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5) 


e Using the Display Physical File Member command. For example, to display the sys/stat.h header 
file, enter the following command: 


DSPPFM FILE(QSYSINC/SYS) MBR(STAT) 


You can print a header file in QSYSINC by using one of the following methods: 


e Using your editor. For example, to print the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION (6) 
e Using the Copy File command. For example, to print the sys/stat.h header file, enter the following 


command: 


CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR (STAT) 


Symbolic links to these header files are also provided in directory /QIBM/include. 
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Errno Values for UNIX-Type Functions 


Programs using the UNIX-type functions may receive error information as errno values. The possible 
values returned are listed here in ascending errno value sequence. 


[Name [Value [Test 

~——— a ee domain error occurred in a math 
function. 

[ERANGE = GE [300200 A [Arangeerror occurred. = error [Arangeerror occurred. = 

—| C _— Data was truncated on an input, output, or 
update operation. 

EN [ENOTOPEN [3004 [Fileisnotopen. is not [Fileisnotopen. 


—— OTREAD — [File i is not opened for read operations. 
EIO [3006 [Input/output error. 


EN [ENODEV [3007 N [Nosuchdevice. [Nosuchdevice. device. 

ae —_ Cannot get single character for files 
opened for record I/O. 

EN [ENOTWRITE [30090 [File is not opened for write operations. is not [File is not opened for write operations. for write operations. 


a —— [The stdin stream cannot be opened. 
[ESTDOUT [3011 [The stdout stream cannot be opened. 


[ESTDERR [30120 [The stderr stream cannot be opened. stderr stream cannot be [The stderr stream cannot be opened. 

_—| a The positioning parameter in fseek is not 
correct. 

[EBADNAME AME [30140 [The object name specified is not correct. — [The object name specified is not correct. — name specified is not correct. 


a ——! The type variable specified on the open 
function is not correct. 


[EBADPOS 3017s [The position specifier is not correct. position [The position specifier is not correct. is not correct. 


17 
EN a — There is no record at the specified 
position. 
ENUMMBRS 3019 Attempted to use ftell on multiple 
members. 
ENUMRECS 3020 The current record position is too long for 
ftell. 
EINVAL 3021 The value specified for the argument is not 
correct. 
EBADFUNC 3022 Function parameter in the signal function 
is not set. 
[302500 


EN [ENOENT T No [No such path or directory, = [No such path or directory, = or directory. 


FoR? ——— ht’ —— ae 
[EPERM  =——<CS~s«LB27_~——SSC«*d Phe Oplerationn is not permitted. = 
[EBADDATA  ——s[3028——Ss[Meessage dataisnotvalid. = 
[EBUSY ==—=«S(38029—s Resource busy, 
[EBADOPT —s*(3040 = Option specified is not valid. 
[ENOTUPD ~—s*([3041 =~‘ File is not opened for update operations. 
[ENOTDLT ~—*[3042. [File is not opened for delete operations. 


EPAD 3043 The number of characters written is 
shorter than the expected record length. 

EBADKEYLN 3044 A length that was not valid was specified 
for the key. 

EPUTANDGET 3080 A read operation should not immediately 
follow a write operation. 

EGETANDPUT 3081 A write operation should not immediately 
follow a read operation. 

[EIOERROR [3101 [A nonrecoverable I/O error occurred. 

[EIORECERR [3 102 [A recoverable I/O error occurred. 

[EACCES [3401 [Permission denied. 


[EN OTDIR [3403 [N ot a directory. 
[ENOSPC [3404 [No space is available. 


[EXDEV [3405 Improper link, [Improperlink, 


[34050 
aa_— 3406 Operation would have caused the process 
to be suspended. 
EWOULDBLOCK 3406 Operation would have caused the process 
to be suspended. 
[3407 


[EINTR [3407 SS s‘[Interrupted function call. [Interrupted function call. call. 


ee— 3408 The address used for an argument was not 
correct. 


[ETIME [3409 [3409 [Operation timedout. [Operation timedout. out. 
—_——— [3415 0 No [No such device oraddress. device [No such device oraddress. address. 
SEs i Pa 
failure 
[ERECURSE [3419 [Recursive attempt rejected. = attempt [Recursive attempt rejected. = 
 ORNESE Si —— see 
[EADDRNOTAVAIL [342200 [Address is notavailable. = [Address is notavailable. = not available. 
ESINOSUORT > pean type of socket is not supported in this 
protocol family. 
[EALREADY [342300 [3423 [Operation is already in progress. = is already in progress. 
REE ABORTED [34240000 [Connection ended abnormally. ended [Connection ended abnormally. 
25 


ECONNRTUSED — aS rma ba tn te 
connect operation 
i ae ce 
reset by that socket 
[EDESTADDRREQ. [3427 00 [3427 | Operation requires destination address. requires [Operation requires destination address. address. 
[EHOSTDOWN [3428s {Ar remote host is notavailable. 
[EHOSTUNREACH [3429 ‘A route to the remote host is not available. 
[EINPROGRESS —[3430. Ss |Operationin progress. = 
[EISCONN «(3431s {A connection has already been established. 
[EMSGSIZE «(3432s [Message size isoutofrange. 
[ENETDOWN  ——s[3433.—s*[ The network currently is not available. 


ENETRESET 3434 A socket is connected to a host that is no 
longer available. 


[ENETUN REACH [3435 [Cannot reach the destination network. 

ENOBUFS 3436 There is not enough buffer space for the 
requested operation. 

ENOPROTOOPT 3437 The protocol does not support the 

specified option. 

ENOTCONN 3438 Requested operation requires a 
connection. 

ENOTSOCK 3439 The specified descriptor does not 
reference a socket. 

[EN OTSUP [3440 [Operation is not supported. 

[EOPN OTSUPP [3440 [Operation is not supported. 


EPFNOSUPPORT 3441 The socket protocol family is not 
supported. 

EPROTONOSUPPORT |3442 No protocol of the specified type and 
domain exists. 

EPROTOTYPE 3443 The socket type or protocols are not 
compatible. 

ERCVDERR 3444 An error indication was sent by the peer 
program. 


[ESHUTDOWN [3445 [Cannot send data after a shutdown. 
[ESOCKTN OSUPPORT [3446 [The specified socket type is not supported. 


ETIMEDOUT 3447 A remote host did not respond within the 
timeout period. 

EUNATCH 3448 The protocol required to support the 
specified address family is not available at 
this time. 


[EBADF = =—S—=«&;3'45——SsDescriptorisnot valid, 
[EMFILE  =—S*[3452,—S——Ss {Too many open files for this process. 
[ENFILE =——=S&3453. Ss [Too many open files inthe system. 
EPIPE == ~—«*(3455, ss (Brokenpipe. 
[ECANCEL =——s«[3456.———s|Operationcancelled. = 
[EEXIST =———s«*(3'KST_—— sie exists, 
[EDEADLK =——s*[3459_ Resource deadlock avoided. 
[ENOMEM ——s«[3460—Ss« Storage allocation request failed. = 
62 


a 34 The synchronization object no longer 
exists because the owner is no longer 
running. 

EDESTROYED 3463 The synchronization object was destroyed, 
or the object no longer exists. 

[ETERM [3464 00—CO [3464 Operation was terminated. = was [Operation was terminated. = 


aes —— OENT1 [3 465 [N o such file or directory. 


ENOEQFLOG 3466 Object is already linked to a dead 
ones sag 


[EEMPTYDIR [3 467 [Directoryisempty. = is empty. 


EMLINK 3468 Maximum link count for a file was 
exceeded. 


ESPIPE  =—~SC~«&346—— “Seek request is not supported for object. 
[ENOSYS —————=«*3470.—S—SSs|Function not implemented. = 
[EISDIR ——i(ass—t*é«*BATALC Specified targetisadirectory, = 
[EROFS =———~—é«i;3B220-—— Read-only file system. 
[EUNKNOWN  —s[3474.— ss [Unknown system state. = 
[EITERBAD  =——s«(34750—— iterator isnotvalid. = 
[EITERSTE  =—sS*(3476 ~—S—SCs=|Iterator is in wrong state for operation. 
[EHRICLSBAD —s [3477 Ss HIRI classisnotvalid. 
[EHRICLBAD ~—s([3478 = {IRI subclassisnot valid. = 
[EHRITYPBAD —[3479 Ss {HRI typeisnotvalid, = 
[ENOTAPPL —=—s*[3480.—~——Ss [Datta requested is not applicable. = 
[EHRIREQTYP  =—[3481_ = {ARI request type isnot valid. 
[EHRINAMEBAD —_ [3482s {HRT resource name isnot valid. 
[EDAMAGE —s([3484.————s [A damaged object was encountered. 
[ELOOP  ———~™—=é«S;3485— SA cop exists in the symbolic links. 
[ENAMETOOLONG [3486 = {Apathnameistoolong, 
[ENOLCK = =——s«*(3487,——s No locksare available. = 
[ENOTEMPTY —*[3488 ~=——Ss[Directory isnotempty. = 
[ENOSYSRSC [3489s System resources are not available. = 
[ECONVERT =— [3490s |Conversionerror, 


[E2BIG [3491 [3491 Ss [Argumentlististoolong, [Argument lististoolong, = is too long. 
—=———— 3492 Conversion stopped due to input character 
that does not belong to the input codeset. 


[ETYPE  ——™ [3493 [3493 |Objecttypemismatche type [Object type mismatch, 
—— 3494 Attempted to reference a directory that 
was not found or was destroyed. 
EBADOBJ 3495 Attempted to reference an object that was 
not found, was destroyed, or was 
damaged. 
EIDXINVAL 3496 Data space index used as a directory is not 
valid. 
[ESOFTDAMAGE [3497 [3497 [Objecthas softdamage. [Objecthas softdamage. soft damage. 


Soe | OTENROLL 3498 User is not enrolled in system distribution 
ies sae———— 


[EOFFLINE = 3499 [3499 |Objectissuspended. is suspended. 


[34990 
oe —— [3 500 [Object i is a read-only object. 


EEAHDDSI 3501 Hard damage on extended attribute data 
space index. 

EEASDDSI 3502 Soft damage on extended attribute data 
space index. 

EEAHDDS 3503 Hard damage on extended attribute data 
space. 

EEASDDS 3504 Soft damage on extended attribute data 

| | ee 


[EEADUPRC [3505 [Duplicate extended attribute record. 


ELOCKED 3506 Area being read from or written to is 
locked. 


[EFBIG [3507 [3507 ss |Objecttoolarge. [Objecttoolarge, large. 
509 


a—_—— 3 The semaphore, shared memory, or 
message queue identifier is removed from 
the system. 

OMSG e The queue does not contain a message of 


the desired type and (msgflg logically 
ANDed with IPC_NOWAIT). 


[EFILECVT = [351k [File ID conversion of a directory failed. ID conversion of a [File ID conversion of a directory failed. failed. 

a——— _— A file ID could not be assigned when 
linking an object to a directory. 

[ESTALE [3513 [File handle was rejected by server. handle was [File handle was rejected by server. by server. 


es} — oes 
[ENOTSIGINIT ——[3516 [Process is not enabled for signals. 

[ECHILD  =———~—=«~S(;B'SS'T.— Ss Nochild process. 
[EBADH = =—sS«(3520.——sHandleisnotvalid, = 


iN YREFS 3523 The operation would have exceeded the 


maximum number of references allowed 
for a descriptor. 


[ENOTSAFE =——s [3524s |Functionisnotallowed. = 
ESC aW—— sk —— pice ee ——— 
[EIRNDAMAGE ~—[3526 Ss |Jourmalisdamaged. 
[EJRNINACTIVE ~— [3527s |Jourmalisimactive, = 
[EIRNRCVSPC [3528 = s‘|Journal space or system storage error. 
[EIRNRMT = ——s*(3529, Ss Journalisremote. 
[ENEWJRNRCV [3530s [New journal receiver isneeded. 
[ENEWJRN  ———s«(3531.=——Ss New journalisneeded. = 
[EJOURNALED [3532s Objectalready journaled. = 
[EIRNENTTOOLONG 3533 [Entry istoolargetosend. 
[EDATALINK —s [3534s [Object is adatalink object. 
[ENOTAVAIL ~—s 3535. IASPisnotavailable. = 


[ENOTTY = OTTY [35360 [I/O control operation is not appropriate. control [I/O control operation is not appropriate. is not appropriate. 

sues 3540 Attempt to write or truncate file past its 
=o ie file size limit. 

[ETXTBSY [35430 [Textfilebusy. file [Textfilebusy. 

SENG OTSET ~— [ASP group not set forthread. [ASP group not set forthread. not set for thread. 


—— a A system call was interrupted and may be 
restarted. 
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